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Tot  - Distribution 
From? Te He Van Vieck 
Date: July 24, 1975 


Subject: Handting Subroutine Errors 


INTRODUCTION 


Multics conventions currenttiy forbid subroutines which may 
be called by many different progrars from performing output 
untess that Is thelr primary purpose. The reason for this rule 
Is the “principte of transparencys” which requlres that the 
subroutine be usable In environments which do not have standard 
I/O attachments, and in environments which wish to use the 
subroutine without obtaining any oufputf. In particular, 
subroutines are currently forbdidden to use com_lerr_ to report 
status. The standard method for reporting status is to supply an 
additional argument to the subroutine which will be set to zero 
or to a standard stetus code by the subroutine. 


The caller of such a subroutine must have some knowled¢ce of 
the cases In which status codes are returned. Often, the caliing 
program has the choice of inctuding a serles of tests for each of 
the possibie statess recognized by the subroutine, or of simply 
assualng that any nonzero status code Indicates that the routine 
falled. When a status code is returned, the calting program 
often wishes fo produce a message describing the sltuation. But 
In some cases, the subroutine can recognize so many different 
Situations that the cailting program will be unable to produce a 
hetpful message without additiona! communicatior between the 
calting program and the subroutine. This problem was encountered 
In the design of delete_,», when deteting a directory. If a 
directory contains Items which cannot be detfeted, there Is 
currentiy no clean way to inform the catter of detete_ of the 
pathname of the item. 


Subroutines which can detect muftipie errors (such as 
conmpliers) have an even more difficult problem. The returning of 
"a status code is suited onty to the detection of singie errors. 
Requiring the catting program to aliecate storage for a usually 
nul? array of stetus Indicators or status messages seems 
uneconomical; and saving the messages In storage allocated by 
the subroutine encounters other problems If muitipie Invocations 
of the routine may exist in the same process. 


Muttics Project internal working cocusentation. Not to be 
reproduced or distr ibuted outside the Muitics Project. 
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When we think of smaft subroutines, fike square root 
programs, these problems can be Ignored or papered over. But 
when farge subsystems are used as subroutines of user application 
programs, the need for a mechanism which allows subroutines and 
subsystems to report status In detalii, white stlifl' allowing the 
calling environment controft over the actual output and the 
content of the message, becomes more and more important. 


PROPOSAL 


To accomplish these goals, a new subroutine is proposed, 
catled sublerr_.» which alit be usec by subroutines in much the 
same way that com_err_ is used by commandse Draft MPM SWG 
documentation is attached. (The “sub” can be considered to be a 
contraction of either “subroutine” or “subsystem.”") A call to the 
subroutine might took tike this’ 


calt sub_lerr_ (code, “sort. Infop, c™, retval, 


“Input record “~d Ignorede“s record_nod$ 


When sub lerr_ is catied, the format string is assembled In the 
same way that ioa_ coes it, a structure is flited In, and the 
condition 


sub_error_ 


ls slgnaltlied. Unilke the call to com_err_» however, sub_err_. 
does not orint the sessage on return from the slgnat; It assumes 
that the environment has disposed of the message. 


The default_error_handier_ for standard Multics processes 
wli! in fact currently print out such a message. However, the 
format of the message currently produced should be lamproved 
silghtty, so that It looks something Uke this? 


name error by caltername ! tocat lone. 
Com_err string. Ioa_ formatted string. 


(Tne message returned by com err. for small Integer codes shoutd 
aiso be changed froma “Code 1 not found in error_tab!fe_" to just 
“Code 1.) For example, the call above alght produce the message 


sort error by sort_!1234% (bound _sort_§ 35677) 
Record too shorte Input record 334 Ignored. 


The sort roufine could use sublerr_ as a way of printing a 
message; or, by adding code which tested the vaiue of retyal, it 
could afiton the user the chance to intercept the error and 
specify, for example, that the record be padded out with btanks. 
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The use of the “retval™ argument Is to allow environsents 
which wish to Intercept the sub_Lerror_ condition and specify 
aifernative action fo the subroutinee The standard environaent 
wlll set retval fo zero. If might be possible to propose a 
future extension to the start command so that the command 


start -return 7. 


would ftocate the condition information structure, set retval to 
7¢ and return to signat_ 


The Introduction of the sub_error_ condition Is In fact a 
conceated Incompatible change for those users who have their own 
default error handlers, since It now becomes a requirement § that 
the handter for subLerror_ understand the “no_pause” switch and 
he able to dispose of the output message. The key step Is fhe 
Inftcaductlan of a new principle, obverse to the orinclple of 
fransparency, which is that every process ought to have a handier 
of tast resort. 


All subroutines which cail sublerr_ should have the fact 
noted in fheir documentations showlng the name and code values 
used in each possibie calif’ and the action taken on return alth 
whatever vatues of refval are alloned. 


Programs which have @ handier for sub_error_ must check the 
condition information structure and be prepared to pass signats 
on If they cannot handte fhem. 
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Name: subd_err_ 


Thls program Is catted by subroutines which which wish to 
report an unexpected sltuation. The subroutine specifies an 
Identifying message and may specify a status code. Switches 
which describe whetter and how to continue execution and a 
polnter to further Information may afso be passed to sub_err_. 
The environment which invoked the subroutine catier of sub_err_ 
may intercept and modify the standard system action taken when 
sub_err_ Is catted. 


Usage! 


del sub_err_ entry options (variable); 


call sub lerr_ (code, name, flagse infope retvals 
ctt_string, loa_args); 


where 

1) code is a status code describing the reason (for 
calling sub_lerr_. code should be ceclared 
fixed bin (35). (Input) 

2) name Is the name of the subsystem or module on 
whose behalf sub_Lerr_ Is calied. name should 
be dectared as a nonvarying character string. 
(Input) 

3) fiags describe tow and whether restart may be 
attempted. Flags shoulc be declared as a 
nonvarying character string. (Input) 

The fallowing vatues are peraltted? 
Cc" continue after printing message. 
To fatai error. No restart allowed. 

4) Infop Is an  optlonal polnter to Information 
specific to the situatlon.e. The standard 
system environment does not use this pointer, 
but It Is provided for the convenlence of 
other environmentse infop should be = an 
atlgned polnter. {tInput) 

5) retval Is a return value from the environment to 


which the error was reported. The standard 
system environment sets this value to zero. 
Other environments may set retval to other 
values, which may be used to select recovery 
strategles. retval should be deciared fixed 
bin (35). (Input/Output) 
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6) ctti_string Is an loa. forrat controlt string which 
defines the messege assoclated with the call 
to sub_err_.- Consu!lf the deserlnotion of loa_ 
In AGS3. cti_string should be declared as a 
nonvarying character stringe (Input) 


7) Loa args are any arguments required for converslon by 
cti_string. (Input) 


Qoeration 


Sub_err_ proceeds as follows: the structure described below 
Is fitted In from the arguments to subLerr_» and the system 
subroutine signal_ Is catted to raise the “sub_error_”“ conditlon. 


When the standard system environment receives a sub_error._. 
signal, it prints a message of the format 


name error by subrnamelfocation 
Status code message. Message fror cti_ string. 


The standard environment then sets retva!l to zero and returns, if 
“c“ was specified; othernise it caltis the tistener. If “start™ 
ls typed, the standard environment will return to sub_err_, which 
will return to the subroutine caller of sub_err_ unitess “f™ was 
specified. If “f° was. specified, sublerr_ wll! signat 
“Litegal_return.” 


Use. by Subsystems 


If an application program wishes to call a subsystem which 
may report errors by sub_Llerr_,. and wishes fo replace the standard 
system action for some ctasses of sub_err_ calls, the appiicatlon 
should estabilsh a handter for the “sub_error_” condition by a 
PL/I ON-statement. When the handter is activated as a resu!t of 
acall to sub_err_ by some dynamic descendant, the nhandier should 
call find _conditlon_info_ to obtain the “software_Info_ptr” which 
“wll! point to a sfructure with the following deciaratfion. 


dc! 14 info atigned based (software_Info_oftr), 
2 tength fixed bin, 
2 version fixed bln, 
2 actlon_filags atigneds 

3 cant_restart bif (1) unal, 

3 default_restart bit (1) unal, 

3 pad bit (34) unat, 

info_string char (256) var, 

code fixed bin (35), 


mn 
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The 


not 


made to the value of Info.retval wlft be returned to the 


2 retval fixed bln (35), 
2 name char (32), 


2 Infop ptrs 


where 
tength 


version 


cant _restart 


default_restart 


pad 


info_string 


code 


retval 


nanze 


lIntop 


handier should 


call continue_to_signali_. 
wishes to intercept thls call to 
wit 


check 
that this particular cali 


page 6 
is the size of the structure in words. 
Ils the version number of the structure. 


This Is version 2. 


is “1i"b If the 
restarted. 


condition cannot be 


is “ib if the standard environment wilt 
print the message and continue execution 
without calling the tistener. 

is padding 


ls the converted message from cti_string 
and loa_argse 


ls the status code. 


is the return vatuee The standard 
environment sets thls vatue to zero. 


is the name of the module encountering 
the conditione 
is a pointer to additloral information 


assoclated with the condition. 


Infoename and Infoecode to make sure 
to sublerr_ Is the one desired, and if 
If the handter determines that it 

sublerr_, the Info structure 


provide the message as converted, switches, etc. Any change 


caller 


of sub_err_ if control returns to sub_err_e 


